Salesforce UX API
TMF622 PATCH - Create Recuring Service Credit
This API is used to apply the service credit/Promotions on products in Aria System
The promotions are applied as recurring discounts on the invoice For specific plan + handset combinations there are Promotions on Installments that can be applied
Note:
- To work this functionality the value of "description" field should be "AdvancedServiceCredits", in request payload.
- The value of "action” under "productOrderItem" should be “noChange” at Master Plan level. And can be “modify/noChange” at supplement-plan level.
- If "productOrderItem.action" is "modify" then ESB will pass this service-credit request to Aria else ignore.
- The service credits are applied as recuring on a product or multiple products ( ESB API will support up to 4 level hierarchy based on productOrderItem ).
URL
https://[localhost]:[port]/sfdc-ux/v1/{businessId}/productOrder/{id}URL PARAM
| name | type | description | required |
|---|---|---|---|
| businessId | string | 2 letter ISO 3166 country code (TT, BB, JM, PA, PR etc.) identifying the business unit. Expected one is "PR"-Puerto Rico | Y |
| id | string | Unique Identifier of the Product Order | Y |
Header
| name | value | description | required |
|---|---|---|---|
| client_id | string | The client_id identifying the channel. | Y |
| client_secret | string | Password associated with the client_id. | Y |
| X-Correlation-ID | string | An identifier for the current call chain that can be used to tie together log entries on multiple layers (e.g. client, server, mainframe). This identifier must be designed to be unique across all applications. | N |
| targetSystem | string | To identify the target BSS. Example: Aria | Y |
| channeId | string | Channel to business. Eg: "SFDC-B2C" | Y |
Request
Service-Credit/Promotion on Supplement-Plan Level
{
"billingAccount": {
"id": "ban0524230-can0524230",
"@type": "AccountRef"
},
"@type": "ProductOrder",
"description": "AdvancedServiceCredits",
"productOrderItem": [
{
"id": "0001",
"action": "noChange",
"@type": "AccountPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_MPI_000",
"name": "Account_Master_Plan"
},
"productOrderItem": [
{
"id": "0001",
"action": "modify",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_110",
"name": "LLA_General_Device",
"description": "Installment|160000048018107",
"productCharacteristic": [
{
"name": "Credit Details",
"valueType": "object",
"value": {
"reasonCode": "1",
"frequency": "36",
"frequencyIntervalType": "1",
"frequencyIntervalLength": "1",
"initialDate": "2024-12-02",
"serviceCodeOption": "2",
"altCallerId": "CreateRecCredit"
}
}
]
},
"itemPrice": [
{
"name": "LLA_General_Device",
"@type": "custom_rates",
"price": {
"dutyFreeAmount": {
"unit": "USD",
"value": 23.99
}
}
}
]
}
]
}
]
}Service Credit/Promotion on multiple Supplement-Plan Level
{
"billingAccount": {
"id": "ban0524230-can0524230",
"@type": "AccountRef"
},
"@type": "ProductOrder",
"description": "AdvancedServiceCredits",
"productOrderItem": [
{
"id": "0001",
"action": "noChange",
"@type": "AccountPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_MPI_000",
"name": "Account_Master_Plan"
},
"productOrderItem": [
{
"id": "0002",
"action": "noChange",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_100",
"name": "PR_B2C_Unlimited_50_Plus"
},
"productOrderItem": [
{
"id": "0003",
"action": "modify",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_110",
"name": "PR_B2C_ULT_50_Plus_MB_Line",
"description": "Service credit for Admin Fee",
"productCharacteristic": [
{
"name": "Credit Details",
"valueType": "object",
"value": {
"reasonCode": "1",
"frequency": "1",
"frequencyIntervalType": "1",
"frequencyIntervalLength": "1",
"initialDate": "2023-05-06",
"serviceCodeOption":"2",
"altCallerId": "CreateRecCredit"
}
}
]
},
"itemPrice": [
{
"name": "PR_B2C_Mobile_Admin_Fee_Voice",
"@type": "custom_rates",
"price": {
"dutyFreeAmount": {
"unit": "USD",
"value": 1.99
}
}
}
],
"productOrderItem": [
{
"id": "0006",
"action": "modify",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_113",
"name": "LLA_General_Device",
"description": "Installment|160000048018107",
"productCharacteristic": [
{
"name": "Credit Details",
"valueType": "object",
"value": {
"reasonCode": "1",
"frequency": "1",
"frequencyIntervalType": "1",
"frequencyIntervalLength": "1",
"initialDate": "2023-05-06",
"serviceCodeOption":"2",
"altCallerId":"CreateRecCredit"
}
}
]
},
"itemPrice": [
{
"name": "LLA_General_Device",
"@type": "custom_rates",
"price": {
"dutyFreeAmount": {
"unit": "USD",
"value": 27.78
}
}
}
]
}
]
}
]
}
]
}
]
}Definitions
| Name | type | Description | required |
|---|---|---|---|
| billingAccount | object | BillingAccount reference. | Y |
| billingAccount.id | string | BAN-CAN number ( Client-defined account identifier ) | Y |
| billingAccount.@type | string | Account Reference | N |
| description | string | A type of order which can be used to place an order. Note - The value must be "AdvancedServiceCredits" always to work this functionality. | Y |
| productOrderItem | array | A list of Product order items | Y |
| productOrderItem.id | string | Unique identifier of a product line item | Y |
| productOrderItem.action | string | Expected valued is "noChange" always. | Y |
| productOrderItem.@type | string | Represents the plan type of the order line item | N |
| productOrderItem.quantity | number | Represents the product line items quantity | N |
| productOrderItem.product | object | Product line details of Master Plan | Y |
| productOrderItem.product.id | string | Represents the product order salesforce instance id | Y |
| productOrderItem.product.name | string | Represents the product catalog id for master plan | N |
| productOrderItem.productOrderItem | array | This object is generated for any underlying supplement/child plan of the Master plan object | Y |
| productOrderItem.productOrderItem. id | string | Y | |
| productOrderItem.productOrderItem. action | string | Expected values either "noChange" or "modify" If action is “noChange” then ESB will ignor the service credit in Aria If action is “modify” then ESB will pass this service-credit request to Aria. | Y |
| productOrderItem.productOrderItem. @type | string | Represents the plan type of the order line item | N |
| productOrderItem.productOrderItem. quantity | string | Represents the product line items quantity | N |
| productOrderItem.productOrderItem. product | object | Product line details of supplement plan | Y |
| productOrderItem.productOrderItem. product.id | string | Client-defined unique eligible plan IDs. | Y |
| productOrderItem.productOrderItem. product.name | string | Represents the product catalog id for supplement plan | Y |
| productOrderItem.productOrderItem. product.productCharacteristic | array | Product Characteristic that go to the plan instance field or non-subscription offer in Aria mapping Please refer the characteristics table below for more info. This object is populated for "@type" Supplement-Plan | Y |
| productOrderItem.productOrderItem. product.productCharacteristic.name | string | Represents the name of the Characteristic | Y |
| productOrderItem.productOrderItem. product.productCharacteristic.valueType | string | Represents the value data type. | N |
| productOrderItem.productOrderItem. product.productCharacteristic.value | object | The value of the Characteristic | Y |
| productOrderItem.productOrderItem. itemPrice | array | This include service credit details. | Y |
| productOrderItem.productOrderItem. itemPrice.name | string | Client-defined unique eligible service id in Aria. Applicable if "@type" is SupplementPlan Eg:PR_B2C_Mobile_Admin_Fee_Voice, LLA_General_Device, etc. | Y |
| productOrderItem.productOrderItem. itemPrice.@type | string | The item price type The "itemPrice.@type" value should be "custom_rates" , else ESB API will ignore this price info to Aria | N |
| productOrderItem.productOrderItem. itemPrice.price | object | This include service credit fee details. | Y |
| productOrderItem.productOrderItem. itemPrice.price.dutyFreeAmount | object | A Money | Y |
| productOrderItem.productOrderItem. itemPrice.price.dutyFreeAmount.value | number | The amount of service credit to create on the account | Y |
| productOrderItem.productOrderItem. itemPrice.price.dutyFreeAmount.unit | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N |
| productOrderItem.productOrderItem. productOrderItem | array | This object is generated for any underlying supplement/child plan of the supplement plan object, Mappings are defined above | N |
| productOrderItem.productOrderItem. productOrderItem.productOrderItem | array | This object is generated for any underlying supplement/child plan of the sub-supplement plan object, Mappings are defined above | N |
| @type | string | Type of the Order | N |
Characteristics Values:
| Name | type | Description | required |
|---|---|---|---|
| reasonCode | string | The reason a given credit was/is to be applied to the account. Allowable values for reason_code: The below are the allowable values as per Aria Values Description 1 General Credit/Other 2 Inadequate Service Delivery 3 Billing / Pricing Issue 4 Service no longer desired 5 Customer Dissatisfaction 6 Installation Issue 9 Customer Return 11 System Testing | Y |
| frequency | string | Number of times the service credit should be applied to the account | N |
| frequencyIntervalType | string | The unit of time associated with the frequency. The below are the allowable values as per Aria Values Description 1 Monthly 2 Bi-monthly 3 Quarterly 4 Semi-annually 5 Annually 6 Weekly 7 Daily | N |
| frequencyIntervalLength | string | Defines the duration between credits. Example: If you pass 4 into this field and 6 (weekly) into the 'frequencyIntervalType' field, then the service credit will be applied every 4 weeks. | N |
| initialDate | datetime | Date on which the recurring service credit should start to be applied | N |
| serviceCodeOption | string | The value of this field will define which service will be used as a template for taxation on the service credit that is created. The below are the allowable values as per Aria If no value is entered in this field, the universal service will be used unless a value is entered in the alt_service_no_to_apply or client_alt_service_id_to_apply field. Then the referenced service will be used instead. Values Description 0 Aria's universal service will be used to apply this service credit which excludes taxes. 2 The service associated with this service credit will match the charge line item. This will result in tax handling that matches the original charge. | N |
| altCallerId | string | value will be "CreateRecCredit" | N |
Response
In this section all the possible data structures received by the client at the moment of responding the method are defined.
Possible response success
This section defines all the possible data structures received by the client and that must be considered satisfactory at the time of responding to the method.
[ 200 ]
OK - PATCH request processed successfully, response body contains an entity corresponding to the requested resource.
Service-Credit/Promotion on Supplement-Plan Level
{
"status": "completed",
"billingAccount": {
"id": "ban0524230-can0524230",
"@type": "AccountRef"
},
"@type": "ProductOrder",
"description": "AdvancedServiceCredits",
"productOrderItem": [
{
"id": "0001",
"action": "noChange",
"@type": "AccountPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_MPI_000",
"name": "Account_Master_Plan"
},
"productOrderItem": [
{
"id": "0001",
"action": "modify",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_110",
"name": "LLA_General_Device",
"description": "Installment|160000048018107",
"productCharacteristic": [
{
"name": "Credit Details",
"valueType": "object",
"value": {
"reasonCode": "1",
"frequency": "36",
"frequencyIntervalType": "1",
"frequencyIntervalLength": "1",
"initialDate": "2024-12-02",
"serviceCodeOption": "2",
"altCallerId": "CreateRecCredit"
}
},
{
"name": "CreditIdInfo",
"valueType": "Object",
"value": {
"creditId": 123456, // newly added field
"recurringCreditNo": 7893456 // newly added field
}
}
]
},
"itemPrice": [
{
"name": "LLA_General_Device",
"@type": "custom_rates",
"price": {
"dutyFreeAmount": {
"unit": "USD",
"value": 23.99
}
}
}
]
}
]
}
]
}Service Credit/Promotion on multiple Supplement-Plan Level
{
"state": "completed",
"billingAccount": {
"id": "ban0524230-can0524230",
"@type": "AccountRef"
},
"@type": "ProductOrder",
"description": "AdvancedServiceCredits",
"productOrderItem": [
{
"id": "0001",
"action": "noChange",
"@type": "AccountPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_MPI_000",
"name": "Account_Master_Plan"
},
"productOrderItem": [
{
"id": "0002",
"action": "noChange",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_100",
"name": "PR_B2C_Unlimited_50_Plus"
},
"productOrderItem": [
{
"id": "0003",
"action": "modify",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_110",
"name": "PR_B2C_ULT_50_Plus_MB_Line",
"description": "Service credit for Admin Fee",
"productCharacteristic": [
{
"name": "Credit Details",
"valueType": "object",
"value": {
"reasonCode": "1",
"frequency": "1",
"frequencyIntervalType": "1",
"frequencyIntervalLength": "1",
"initialDate": "2023-05-06",
"service_code_option": "2",
"altCallerId": "CreateRecCredit"
}
},
{
"name": "CreditIdInfo",
"valueType": "Object",
"value": {
"creditId": 123456, // newly added field
"recurringCreditNo": 7893456 // newly added field
}
}
]
},
"itemPrice": [
{
"name": "PR_B2C_Mobile_Admin_Fee_Voice",
"@type": "custom_rates",
"price": {
"dutyFreeAmount": {
"unit": "USD",
"value": 1.99
}
}
}
],
"productOrderItem": [
{
"id": "0006",
"action": "modify",
"@type": "SupplementPlan",
"quantity": 1,
"product": {
"id": "ban0524230-can0524230_113",
"name": "LLA_General_Device",
"description": "Installment|160000048018107",
"productCharacteristic": [
{
"name": "Credit Details",
"valueType": "object",
"value": {
"reasonCode": "1",
"frequency": "1",
"frequencyIntervalType": "1",
"frequencyIntervalLength": "1",
"initialDate": "2023-05-06",
"service_code_option": "2",
"altCallerId": "CreateRecCredit"
}
},
{
"name": "CreditIdInfo",
"valueType": "Object",
"value": {
"creditId": 8943993, // newly added field
"recurringCreditNo": 8233533 // newly added field
}
}
]
},
"itemPrice": [
{
"name": "LLA_General_Device",
"@type": "custom_rates",
"price": {
"dutyFreeAmount": {
"unit": "USD",
"value": 27.78
}
}
}
]
}
]
}
]
}
]
}
]
}Definiotions
| Name | type | Description | required |
|---|---|---|---|
| state | string | acknowledge on order creation. | N |
| object | Complete request payload will be return as response along with below few additional fields will be come. | N | |
| productOrderItem.product.productCharacteristic | array | Product Characteristic will contain the credit Id details . | N |
| productOrderItem.product. productCharacteristic.name | string | Name of the Characteristic | N |
| productOrderItem.product. productCharacteristic.valueType | string | Data type of this Characteristic | N |
| productOrderItem.product. productCharacteristic.value | object | Value of the Characteristic | N |
Characteristics Values:
| Characteristic Name | type | Description | required |
|---|---|---|---|
| creditId | number | Aria-assigned unique identifier of credit Id | N |
| recurringCreditNo | number | The identifier for the recurring credit. | N |
Possible response error
In this section all the possible data structures received by the client are defined and that must be considered as unsatisfactory when responding to the method.
[ 400 ]
Bad Request - the request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
{
"errors" : [{
"code" : 400,
"message" : "The request is invalid or not properly formed.",
"description" : "Malformed request syntax, invalid request message framing, or deceptive request routing."
}]
}[ 401 ]
Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
{
"errors" : [{
"code" : 401,
"message" : "The user could not be authenticated for this request.",
"description" : "The request has not been applied because it lacks valid authentication credentials for the target resource"
}]
}[ 403 ]
Forbidden - Indicates that the server understood the request but refuses to fulfill it. If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials.
[ 404 ]
Not Found - server has not found a resource with that URI. This may be temporary and permanent condition. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
{
"errors" : [{
"code" : 404,
"message" : "APIKIT:NOT_FOUND",
"description" : "The requested operation failed because a resource associated with the request could not be found."
}]
}[ 405 ]
Method Not Allowed - HTTP method not allowed for this resource. The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
{
"errors": [{
"code": 405,
"message": "APIKIT:METHOD_NOT_ALLOWED",
"description": "HTTP Method PUT not allowed for : /{businessId}/productOrder/{id}"
}]
}[ 500 ]
Internal Server Error - server encountered an error processing request. This should not happen normally, but it is a generic error message, given when no more specific message is suitable.
{
"errors" : [{
"code" : 500,
"message" : "The request failed due to an internal error.",
"description": "Internal Server Error"
}]
}[ 501 ]
Not implemented - indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.
{
"errors" : [{
"code" : 501,
"message" : "Not implemented",
"description" : "Operation PATCH /{businessId}/productOrder/{id} for Business Id: xxxx not implemented"
}]
}[ 502]
Bad Gateway - gateway is available but backend service is not. The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
[ 503 ]
Service Unavailable - temporary maintenance of service, try again later. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay will be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response. Note: The existence of the 503 status code does not imply that a server will use it when becoming overloaded. Servers may simply refuse the connection.
Retry-After: 120